@Agent、@Action、@AchievesGoal 的工程語意

今天要解決的問題

• record 是資料邊界
• annotation 宣告能力
• 方法簽章就是流程約束

觀念圖解

Embabel 的流程不是藏在 prompt 裡，而是寫在 Java 方法簽章與 annotation 上。

record 代表重要的中間資料，例如查詢、活動紀錄、摘要、方案草稿與審核結果。action 的參數表示它需要什麼，回傳值表示它產生什麼。

annotation 則把這些方法標成 planner 看得懂的能力：哪個類別是 agent、哪些方法是 action、哪個 action 能達成 goal。這樣流程就能被閱讀、測試與追蹤。

Embabel 的開發體驗很接近 Spring 團隊熟悉的風格：用 annotation 宣告元件，用方法簽章描述能力，用 record 定義資料。@Agent 標示一組能力，@Action 標示可被 planner 使用的步驟，@AchievesGoal 標示終端目標。

最重要的是不要把 action 寫成一個萬用的 void function(String input)。這樣雖然能跑，但 planner 無法理解中間狀態。更好的做法是讓每個 action 的參數與回傳值都具體化(類別型態)，例如 ActivitySummary summarize(TravellerActivity activity)。

這種設計讓測試也自然切開。純 Java action 可以直接單元測試；LLM action 可以測 prompt 組裝、模型角色與工具暴露；整條 flow 可以用 input-to-goal 的整合測試驗證。

程式碼補充

這一段改從 annotation 與型別宣告的角度說明 planner 如何理解 action。

宣告語意才是這一段的核心：@Agent 告訴系統這是一組能力，@Action 告訴 planner 這一步可以被規劃，@Cost 則是讓 action 在被選路時帶有偏好。annotation 不是裝飾，而是讓程式碼變成 planner 看得懂的 metadata。

record 到底怎麼宣告，裡面該放什麼

• record 最適合放「這一步要交換的資料」
• 欄位只放 planner、action、LLM 真的需要讀到的內容
• 不要把 service、Repository、暫時旗標或萬用 Map 塞進去

record CustomerQuery(Long customerId, String question) {}

record TravellerActivity(
    String customerName,
    Instant from,
    Instant to,
    List<Trip> trips
) {}

record ActivitySummary(
    String summary,
    boolean highSpender,
    boolean frequentTraveler
) {}

看這三個例子就夠了：CustomerQuery 放查詢對象與問題，TravellerActivity 放報表查回來的期間與旅遊資料，ActivitySummary 放摘要結果與後續流程會用到的判斷欄位。原則很簡單，下一個 action 需要什麼，就放什麼；下一個 action 不會看，也不該由這個型別負責的，就不要放。

如果是 OfferDraft、ReviewedOffer 這類後面階段的型別，也維持同一個標準：只描述該階段的結果形狀。這樣 blackboard 上每個物件都會很清楚，planner 才能靠型別推導流程。

只補 annotation 的局部形狀

@Agent(description = "Customer care flow")
class CustomerCareAgent {

    @Action
    ActivitySummary summarize(TravellerActivity activity) { ... }

    @AchievesGoal(description = "Produce reviewed offer")
    @Action
    ReviewedOffer review(OfferDraft draft) { ... }
}

這段只保留今天需要看的重點：類別層有 @Agent，中間步驟有 @Action，最後終點再加上 @AchievesGoal。讀者先看懂「標記的工程語意」，就不會被完整實作分散注意力。

record 應該放在哪裡

真正專案裡，這些 record 最好各自獨立成檔，通常放在 domain 或 model package。不要全部塞進 agent 類別裡面，否則後面要共用、加 @Tool、寫測試時會很快變亂。

今日實作 / 思考任務

用 5 個 record 與 4 個 action 寫出 CustomerCareAgent 的骨架，不需要先接真模型，先讓型別流動清楚。

如果你也想進一步學習如何透過 AI 開發 Spring Framework 應用，讓 AI 協助理解框架、撰寫程式、除錯與驗>證，歡迎到 Hahow 看凱文大叔的最新課程【駕馭 AI 的全端實戰養成班：從零打造企業級智慧應用系統】。一起>學習如何駕馭 AI，提升 Spring 應用的開發效率與品質。
課程連結